Data Types for Navigation Services

When your application calls a Navigation Services function that creates a dialog box, you pass a pointer to a NavReplyRecord structure. Navigation Services, in turn, uses this structure to provide your application with information about the user's interactions with the dialog box. When your application is through using the structure, remember to dispose of it by calling the function NavDisposeReply .

Field descriptions

version: Identifies the version of this structure.
validRecord: A Boolean value of true if the user closes a dialog box by pressing Return or Enter, or by clicking the default button in an Open or Save dialog box. If this field is false , all other fields are unused and do not contain valid data.
replacing: A Boolean value of true if the user chooses to save a file by replacing an existing file (thereby necessitating the removal or renaming of the existing file).
isStationery: A Boolean value informing your application whether the file about to be saved should be saved as a stationery document.
translationNeeded: A Boolean value indicating whether translation was or will be needed for files selected in Open and Save dialog boxes.
selection: An Apple event descriptor list (AEDescList ) created from references to items selected through the dialog box. Navigation Services creates this list, which is automatically disposed of when your application calls the function NavDisposeReply . You can determine the number of items in the list by calling the Apple Event Manager function AECountItems . Some dialog boxes may return one or more items; a Save dialog box will always return one. Each selected HFS file object is described in an AEDesc structure by the descriptor type typeFSS . You can coerce this descriptor into an FSSpec structure to perform operations such as opening the file. For more information, see Obtaining Object Descriptions. For more information on Apple event structures and functions, see Inside Macintosh: Interapplication Communication . For more information on FSSpec structures, see Inside Macintosh: Files .
keyScript: The keyboard script system used for the filename. For information on script codes, see Inside Macintosh: Text .
fileTranslation: A handle to a Translation Manager structure of type FileTranslationSpec . This structure contains a corresponding translation array for each file reference returned in the selection field. When opening files, Navigation Services will perform the translation automatically unless you set the kNavDontAutoTranslate flag in the dialogOptionFlags field of the NavDialogOptions structure Configuration Option Constants . When Navigation Services performs an automatic translation, the FileTranslationSpec structure is strictly for the Translation Manager's use. If you turn off automatic translation, your application may use the FileTranslationSpec structure for your own translation scheme. If the user chooses a translation for a saved file, the FileTranslationSpec structure contains a single translation reference for the saved file and the translationNeeded field of the NavReplyRecord structure is set to true . The handle to the FileTranslationSpec structure is locked, so you can safely use dereferenced pointers. For more information, see Translating Files on Open and Translating Files on Save . For information on the FileTranslationSpec structure, see Inside Macintosh: More Macintosh Toolbox .

NavDialogOptions

The NavDialogOptions structure contains dialog box configuration settings you can pass to several Navigation Services functions.



 
struct NavDialogOptions {

    UInt16 version;

    NavDialogOptionFlags dialogOptionFlags;

    Point   location;

    Str255  clientName;

    Str255  windowTitle;

    Str255  actionButtonLabel;

    Str255  cancelButtonLabel;

    Str255  savedFileName;

    Str255  message;

    UInt32  preferenceKey;

    Handle  popupExtension;

};

Field descriptions

version: Identifies the version of this structure. Be sure to specify the kNavDialogOptionsVersion constant in this field.
dialogOptionsFlags: One of several constants defined by the NavDialogOptionFlags data type as described in Configuration Option Constants .
location: The upper-left location of the dialog box (in global coordinates). If you set the dialogOptionFlags field to NULL or set this field to (-1,-1), then the dialog box appears in the same location as when last closed. The size and location of the dialog box is persistent, but defaults to opening in the middle of the main screen if any portion is not visible when opened at the persistent location and size. For more information, see Persistence.
clientName: A string that identifies your application in the dialog box window title.
windowTitle: A string that you can provide to override the default window title.
actionButtonLabel: An alternative button title for the dialog box's action button. If you do not specify a label, the button will use the default label (Open or Save, for example.)
cancelButtonLabel: An alternative button title for the Cancel button in dialog boxes.
savedFileName: The default filename for a saved file.
message: The string for the banner, or prompt, below the browser list. This message can provide more descriptive instructions for the user. If you don't provide a message string, the browser list expands to fill that area.
preferenceKey: An application-defined value that identifies which set of dialog box preferences Navigation Services should use. If your application maintains multiple sets of preferences for a particular type of dialog box, you can determine which set is active by specifying the appropriate value in the preferenceKey field. For example, an application may allow one set of preferences when it calls the function NavGetFile to open text files and a different set of preferences when opening movie files. If you do not wish to provide a preference key, specify zero for the preferenceKey value.
popupExtension: A handle to one or more structures of type NavMenuItemSpec used to add extra menu items to the Show pop-up menu in an Open dialog box or the Format pop-up menu in Save dialog boxes. Using NavMenuItemSpec structures allows your application to add additional document types to be opened or saved, or different ways of saving a file (with or without line breaks, for example). For more information, see Customizing Type Pop-up Menus.

NavMenuItemSpec

Your application uses theNavMenuItemSpec structure to define additional items in an Open dialog box's Show pop-up menu or a Save dialog box's Format pop-up menu. For a description of how to add menu items, see Customizing Type Pop-up Menus. For information about file creators and file types, see Inside Macintosh: Macintosh Toolbox Essentials .



 
struct NavMenuItemSpec {

    UInt16  version;

    OSType  menuCreator;

    OSType  menuType;

    Str255  menuItemName;

};

Field descriptions

version: Identifies the version of this structure. Be sure to specify the kNavMenuItemSpecVersion constant in this field.
menuCreator: A value set by your application. This is a unique tag that Navigation Services passes back to your application to identify the application type of the selected menu item.
menuType: A value set by your application. This is a unique tag that Navigation Services passes back to your application to identify the file type of the selected menu item.
menuItemName: The item name that appears in the pop-up menu.

NavFileOrFolderInfo

The NavFileOrFolderInfo structure contains file or folder information for use by your application-defined filter function. For more information, see Filtering File Objects.



 
struct NavFileOrFolderInfo {

    UInt16  version;

    Boolean isFolder;

    Boolean visible;

    UInt32  creationDate;

    UInt32  modificationdate;

    union {

        struct {

            Boolean     locked;         /* file is locked */

            Boolean     resourceOpen;   /* resource fork is open */

            Boolean     dataOpen;       /* data fork is open */

            Boolean     reserved1;      

            UInt32      dataSize;       /* size of data fork */

            UInt32      resourceSize;   /* size of resource fork */

            FInfo       finderInfo;     /* see IM: MTE */

            FXInfo      finderXInfo;    /* see IM: MTE */

        }           fileInfo;

        struct {

            Boolean     shareable;      /* volume can be shared */

            Boolean     sharePoint;     /* volume is being shared */

            Boolean     mounted;        /* volume is mounted */

            Boolean     readable;       /* volume is readable */

            Boolean     writeable;      /* volume is writeable */

            Boolean     reserved2;      

            UInt32      numberOfFiles;  /* number of files in folder */

            DInfo       finderDInfo;    /* see IM: MTE */

            DXInfo      finderDXInfo;   /* see IM: MTE */

            char        reserved3[214]; /*

        }           folderInfo

    }           fileAndFolder;

};



typedef struct NavFileOrFolderInfo  NavFileOrFolderInfo;

Note

The information in this structure is valid only for HFS file objects.

NavCBRec

The NavCBRec structure provides customization information for your application-defined functions.



 
struct NavCBRec {

    UInt16 version;

    NavContext context;

    WindowPtr window;

    Rect customRect;

    Rect previewRect;

    NavEventDataInfo eventData;

};

Field descriptions

version: Identifies the version of this structure.
context: A pointer to a value set by your application. Your application passes this value in the context parameter of the function NavCustomControl . When Navigation Services calls your event-handling function, your application can obtain this value from the context field.
window: A pointer to the Navigation Services dialog box that generated the call to your application-defined function.
customRect: A local coordinate rectangle describing the customization area available to your application. This determines how much room your application has to install custom controls. For more information on using this field, see Adding Custom Controls.
previewRect: A local coordinate rectangle describing the preview area available to your application's preview function. The minimum size is 145 pixels wide by 118 pixels high.
eventData: A structure of type NavEventData .

NavEventData

The NavEventData structure contains a structure of type NavEventDataInfo ; in Navigation Services 1.1, the NavEventData structure also contains a field describing the dialog box item last clicked by the user.



 
struct NavEventData {

    NavEventDataInfo eventDataParms;

    SInt16 itemHit;                     /* Nav Svcs 1.1 ONLY */

};



typedef struct NavEventData     NavEventData

eventDataParms: A structure of type NavEventDataInfo .
itemHit: A signed integer value. On return, this value represents the item number of the dialog box item last clicked by the user. If the user clicks something other than a valid Navigation Services-generated control item, this value will be -1. Use the function NavLibraryVersion to ensure Navigation Services 1.1 is installed before you attempt to use this data.

NavEventDataInfo

The NavEventDataInfo structure provides event-handling data to your application.



 
union NavEventDataInfo {

    EventRecord *event;

    void *param;

};



typedef struct NavEventDataInfo     NavEventDataInfo;

event: A pointer to the EventRecord structure describing an event to be handled by your event-handling function.
param: A pointer to additional event data. In most cases, this data consists of an Apple event descriptor list (AEDescList ) for the file or files affected by the event described in the event field. For example, if the event consists of the user making a selection in the browser list, the AEDescList specifies the file or files selected.

NavTypeList

Your application uses the NavTypeList structure to define a list of file types that your application is capable of opening. Your application passes a pointer to this list to Navigation Services functions that display Open or Save dialog boxes. You may create this list dynamically or reference a Translation Manager 'open' resource.

For a description of how to use the NavTypeList structure, see Providing File Opening Options. For more information on the'open' resource and the Translation Manager, see the "Translation Manager" chapter in Inside Macintosh: More Macintosh Toolbox.



 
struct NavTypeList {

    OSType  componentSignature;

    short   reserved;

    short   osTypeCount;

    OSType  osType[1];

};

Field descriptions

componentSignature: Your application signature.
osTypeCount: Number indicating how many file types are defined.
osType: A list of file types your application can open.

NavEventProcPtr

If you create an event-handling function, it must accept certain input parameters, as defined by the NavEventProcPtr data type. For more information on implementing an event-handling function, see MyEventProc. For a sample code listing, see A sample event-handling function.



 
typedef pascal void (*NavEventProcPtr) 

                    ( NavEventCallbackMessage callBackSelector,

                    NavCBRecPtr callBackParms, 

                    void *callBackUD);

NavPreviewProcPtr

If you create a preview function, it must accept certain input parameters, as defined by the NavPreviewProcPtr data type. For more information on implementing a preview function, see MyPreviewProc.



 
typedef pascal Boolean  (*NavPreviewProcPtr) 

                        ( NavCBRecPtr callBackParms, 

                        void *callBackUD );

NavFilterProcPtr

If you create a filter function, it must accept certain input parameters, as defined by the NavFilterProcPtr data type. For more information on implementing a filter function, see MyFilterProc. For a sample code listing, see A sample filter function.



 
typedef pascal Boolean (*NavObjectFilterProcPtr)

                        (AEDesc *theItem, 

                        void *info, 

                        void *callBackUD,

                        NavFilterModes filterMode);